Early releases of the nShell contained sample code for the Think C development environment. This Note describes how to build nShell commands using Think Pascal.
Examples
========
Example projects have been released in a package called "nShell(tm) Think Pascal Examples". This package contains example projects in Think Pascal, as well as C source code for the new "nShell.lib".
The Interface
=============
The general interface for nShell commands is described in the "Programmer's Guide to the nShell". For this Pascal interface, a new library (nShell.lib) was written to translate nShell variables and functions from C into Pascal. The differences between the Pascal interface and the general one are discussed below:
A New Main
----------
The nShell.lib now contains the true "main" of the nShell command. This main routine sets up the environment and calls a Pascal routine:
This new procedure is the new "main" for Pascal commands. This routine is responsible for managing the nshc_parms "action" and "result" variables, as well as performing any command-specific tasks.
A New nshc_parms
----------------
The data interface for commands has been translated into Pascal, and is defined in the file "nshc.p". Variables within this structure follow the roles set out in the Programmer's Guide.
A New nshc_calls
----------------
A new callback interface has been written for Pascal commands. Calls are now made through the "nShell.lib". Definitions for these routines are found in the file "nshc.p". The nshc_calls pointer may not be used directly, but is passed in each call to the library.
Each call requires that the nshc_calls pointer be passed as the first parameter. To ease typing, a shorter name could be used for the call pointer, or macros could be defined to eliminate it entirely.
This routine prints a c-style, null-terminated, string to stderr. The string buffer should be defined as: "foo : packed array[x..y] of char". The call may then be made using the @ operator: "NSH_puts_err( nshc_calls, @foo );
This routine prints a c-style, null-terminated, string to stdout. The string buffer should be defined as: "foo : packed array[x..y] of char". The call may then be made using the @ operator: "NSH_puts( nshc_calls, @foo );
This routine prints a Pascal string to the stdout device.
input from stdin
================
NSH_getchar
-----------
function NSH_getchar (nshc_calls: t_nshc_calls): integer;
This routine collects a single character from stdin. Returns:
0 = No character available
-1 = End of input
others = Next character in queue
*** NOTE: An error in nShell versions prior to v1.0.2 caused a ^D key to be returned directly (04 decimal), and not to be converted to -1. ***
NSH_gets
--------
function NSH_gets (nshc_calls: t_nshc_calls; c_string: ptr; size: integer): integer;
This routine collects a c-style string from stdin. The string buffer should be defined as: "foo : packed array[x..y] of char". The call may then be made using the @ operator: "NSH_gets( nshc_calls, @foo, size );". The "size" field defines the maximum length of the input string. Returns:
0 = No character available
-1 = End of input
others = Length of input string
NSH_getStr
----------
function NSH_getStr (nshc_calls: t_nshc_calls; s: Str255): integer;
This routine collects a 255 character Pascal-style string from stdin. Returns:
0 = No character available
-1 = End of input
others = Length of input string
variable access functions
=========================
NSH_var_set
-----------
function NSH_var_set (nshc_calls: t_nshc_calls; name: Str32; value: Str255): integer;
Assigns the "value" string to a variable of the given "name". If a matching variable is not found, a new one will be created. Returns: 0 = success, -1 = could not create variable.
NSH_var_unset
-------------
function NSH_var_unset (nshc_calls: t_nshc_calls; name: Str32): integer;
Removes the variable of the given "name". Returns: 0 = found and cleared, 1 = could find create variable.
NSH_var_env
-----------
function NSH_var_env (nshc_calls: t_nshc_calls; name: Str32; value: Str255): integer;
Searches for a variable of the given "name", and returns its "value". Returns: 0 = success, 1 = could find create variable.
path expansion functions
========================
NSH_path_expand
---------------
function NSH_path_expand (nshc_calls: t_nshc_calls; path: Str255): integer;
Expands a full or partial "path" in place. Returns: 0 = success or 1 = failure.
NSH_path_to_FSSpec
------------------
function NSH_path_to_FSSpec( nshc_calls: t_nshc_calls; path: Str255; spec: FSSpecPtr): integer;
Expands a full or partial "path" in place. Returns: 0 = success or 1 = failure.
NSH_path_which
--------------
function NSH_path_which (nshc_calls: t_nshc_calls; cmd_path: Str255): integer;
Follows the command search path, and expands a full or partial "cmd_path" in place. Returns: 0 = success or 1 = failure.
Pop a modal dialog containing the given string. The dialog may be given one of three sizes: 0 = small, 1 = medium, 2 = large.
NSH_ask
-------
function NSH_ask (nshc_calls: t_nshc_calls; s: Str255; size: integer): integer;
Pop a three button modal dialog containing the given string. The three buttons are "Yes", "No", and "Cancel". The dialog may be given one of three sizes: 0 = small, 1 = medium, 2 = large. Returns: 1 = yes, 2 = no, 3 = cancel.
misc
====
NSH_match
---------
function NSH_match (nshc_calls: t_nshc_calls; pattern: Str255; target: Str255): integer;
The given "pattern" is compared against the "target" according to shell wildcard rules. Returns: 0 = match, 1 = no match.
